Dynamic Alerts are very similar to the Macintosh’s alerts, only they are much better in most situations. They automatically change size and shape to accommodate the text that is displayed in them, and they are always centered on the main monitor. It’s like having hundreds of custom alerts available, without having to design any of them!
When a Dynamic Alert is displayed, it optionally beeps the user and the cursor is changed to the Macintosh arrow. The alert box is automatically sized to accommodate the text specified by your application, and it is centered on the main monitor to be aesthetically pleasing. An icon can optionally be displayed in the top left corner of the alert. Your application specifies the combination of buttons that appear at the bottom of the alert.
The AlertBox function automatically polls for mouse clicks and typing events. When the user clicks one of the buttons, or types Return or Enter to activate a default button, the alert box disappears and control is returned to your application. The AlertBox function returns the value of the button that was selected by the user.
Icons
`````
When Tools Plus draws the icon in the Dynamic Alert, it does so by accessing an icon family and by being sensitive to the settings of the monitor on which the icon is being displayed. This means that it displays the best available icon (cicn, icl8, icl4, ICN#, or ICON resource) for the target monitor. You can define ‘cicn’ or ‘icl8’ icons for use with monitors set to 8-bits or higher, ‘icl4’ icons for monitors set to 4-bits or higher, and ‘ICN#’ or ‘ICON’ icons for monitors set to 1-bit or higher. For more details about how icons are displayed, see the DrawIcon procedure which is used by AlertBox to draw the icon.
The System file includes 3 icons that are ready for your use. These are the “stop”, “note”, and “caution” icons as illustrated below. Constants have been defined to let you use these system icons without system compatibility concerns.
Text
````
The text displayed by Dynamic Alerts is automatically split into multiple lines by using word-wrap if necessary. AlertBox adjusts the box’s width to make the length of multiple lines as similar as possible. A Carriage Return (ASCII code $0D) can be used within the text to start a new line. You can use the ReturnKey constant to make your program more readable. This lets you form an alert box with multiple lines of text by using a single line of source code in your program.
A Dynamic Alert’s text is left-aligned unless it has no buttons, in which case the text is centered.
Buttons
```````
Dynamic Alerts can display up to three buttons, including an optional default button. The default button is outlined with a border and is automatically selected if the user presses the Return or Enter key. Several common button combinations have been defined for you as constants. Later in this manual, you will be shown how to define your own button combinations.
Function’s Value
````````````````
The AlertBox function returns with a value that indicates which button was clicked by the user. If AlertBox displays an alert with no buttons, it returns with a value of 1. Constants have been defined to let your application match the function’s value to a button name more easily.
Automatic User Notification
```````````````````````````
If your application is running under System 6’s MultiFinder or System 7, Dynamic Alerts automatically make use of the Macintosh toolbox’s Notification Manager. The Notification Manager is used to tell the user that there is something happening they need, or want to be aware of in an inactive application. An example of the Notification Manager at work is when Print Monitor tells your application it needs a sheet of paper to be inserted for a manual page feed.
If your application is inactive when it uses the AlertBox routine, Tools Plus notifies the user by displaying a notification dialog. Your application can customize the notification by using the SetNotification routine.
pascal pascal short AlertBox (short theIcon, Str255 AlertText,
long AlertCode);
function AlertBox (theIcon: INTEGER; AlertText: STRING;
AlertCode: LONGINT): INTEGER;
TheIcon is the icon ID that is displayed in the alert. If the icon ID you specify does not exist, then the noteIcon is displayed in its place. Your application can specify any icon it wants, providing the icon resource exists in either the System file or your application. For more details about how the icon is drawn, see the DrawIcon procedure which is used by AlertBox to draw the icon.
AlertText is the text that is displayed in the Dynamic Alert. A Carriage Return (ASCII code $0D) can be used in the text to start a new line. You can use the ReturnKey constant to make your program more readable. A Dynamic Alert’s text is left-aligned unless the alert has no buttons, in which case the text is centered.
AlertCode specifies the button layout that appears in the Dynamic Alert. See “Custom Button Combinations” (below) to define your own button layouts.
The AlertBox function returns with a value that indicates which button was clicked by the user. If AlertBox displays an alert with no buttons, it always returns with a value of 1. Constants have been defined to let your application match the function’s value to a button name more easily.
Custom Button Combinations
``````````````````````````
AlertCode lets you specify the button layout that appears on Dynamic Alerts. This code is a long integer whose value is broken into 5 single-digit numbers, each of which specifies something about the button combination.
(1) Number of buttons displayed in the alert [0 to 3]
/
/ (2) Default button position [1 to 3, from right to left]. 0 if no
| / default button
| /
|/ (3) 1st button name [from 1 to 7, rightmost button]. 0 if no
|| / button in this position.
|| /
||/ (4) 2nd button name [from 1 to 7, second from right]. 0 if no
||| / button in this position.
||| /
|||/ (5) 3rd button name [from 1 to 7, third from right]. 0 if no
|||| / button in this position.
|||| /
||||/
33243 AlertCode means: 3 buttons in the alert
3rd button from right is the default
button #2 (Cancel) is 1st button from right
button #4 (No) is 2nd button from right
button # 3 (Yes) is 3rd button from right
(the default)
Single button alerts have the button centered between the left and right side of the alert box. Two button alerts have their buttons placed side by side in the bottom right corner of the alert. Three button alerts have the first button placed on the bottom right side of the box, and the next two are paired off further to the left.
If the AlertCode is negative, the Dynamic Alert doesn’t beep when displayed. We strongly recommend that you define your own custom alert codes as constants, then use those constants throughout your application to make your source code more readable.
CONST {Icon IDs for alert icons… }
NoIcon =-32768 {no icon displayed in alert box }
stopIcon = 0; {stopIcon will automatically access }
noteIcon = 1; { ID = 3 in system files version 5 }
Tools Plus provides seven different button titles that may be used in various combinations on dynamic alert boxes. Although button titles and button number constants are provided for only seven buttons (as detailed in AlertBox), a total of nine buttons are available for use.
Button specifies the button number (from 1 to 9) that is affected.
Title specifies the button’s title that will appear on all subsequent Dynamic Alerts. The title may be up to 9 characters long. The size of the buttons on a dynamic alert box does not change to accommodate longer titles. The specified title stays in effect until it is explicitly changed by your application. If a null string is provided, the button resumes its default title.
Your application can rename any or all the button titles as required, but keep in mind that the constants defined for the AlertCode and buttons will not work correctly because buttons have been renamed.
